home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _editors / editors / _zap / !Zap / Docs / E-File < prev    next >
Text File  |  1994-03-23  |  10KB  |  256 lines
  1. *************************************************************************
  2. * >E-File    Documents a file block format                *
  3. *************************************************************************
  4.  
  5. By convention, file blocks are pointed to by R9. However, whenever a file is
  6. created, the file block pointers of the other files may change. Hence these
  7. pointers are not preserved across calls to Wimp_Poll. Thus they must be
  8. converted to file block 'offsets' (ie 0=first file,1=second etc) for storing
  9. as pointers or links. The calls Zap_ConvFileOff and Zap_GetFileOff can be
  10. used to do this. The number of valid file block offsets may be got by
  11. Zap_ReadVar. (Then valid offsets are 0 1 ... n-1)
  12.  
  13. The length of a file block is not fixed and varies across versions of zap.
  14. Thus you must not assume a fixed length. If you must know the length then
  15. convert file offsets 0,1 to pointers and then subtract them. The offsets from
  16. the file block start are given names beginning with 'f_'.
  17.  
  18. See the E-Library file for a list of the 'f_' names. You should use code of
  19. the form:
  20.  
  21.     LDR R0,[R9,#f_ptr]        \ set R0 to start of file buffer.
  22.     
  23. to read these variables.
  24.  
  25. The files themselves are stored in SPLIT BUFFER format. This means that the
  26. file data is split in two, with a gap in the middle. The diagram below should
  27. illustrate this.
  28.  
  29.         ------------------------ f_ptr+f_bufl
  30.         | top half of file     |
  31.         ------------------------ f_ptr+f_splite
  32.         | file gap           |
  33.         ------------------------ f_ptr+f_splito
  34.         | bottom half of file  |
  35.         ------------------------ f_ptr
  36.         
  37. NB For all Zap data structures block_start=first byte of data, block_end=
  38. last byte of data+1, block_length=block_end-block_start.
  39.  
  40. Note that f_ptr may change on any heap block claim, or file insert/delete.
  41. Thus all the other variables are stored as offsets from this. You should use
  42. the call Zap_SplitBuffer to change the buffer length or split position. You
  43. should use the call Zap_Command to insert/delete data. Inserting data
  44. manually and keeping all the variables/undo buffer/screen updated requires a
  45. lot of code if you want to do it yourself (the only exception to this is the
  46. e_postload/e_presave calls where it is quicker to manipulate the file
  47. directly).
  48.  
  49. For most subs in Zap, a position in the file is given as an offset from the
  50. file start (in the range 0 to the length of the file). These file offsets
  51. should not be confused with the file block offsets described in the first
  52. paragraph. When I say 'file offset', it should be clear from the context what
  53. I mean.
  54.  
  55. To read the byte at offset R0 you should use code of the form:
  56.  
  57.     REM R0=file offset R9=file
  58.     REM On exit R1 corrupted and R0=byte read.
  59.  
  60.     LDR R1,[R9,#f_splito]        \ find the split offset in the buffer
  61.     CMP R0,R1            \ are we in the bottom or top half?
  62.     LDRCS R1,[R9,#f_splits]
  63.     ADDCS R0,R0,R1            \ if in the top half, skip the split
  64.     LDR R1,[R9,#f_ptr]        \ start address of file
  65.     LDRB R0,[R1,R0]            \ read the byte
  66.  
  67. To read multiple bytes you should obviously use more efficient code! If
  68. you are doing a very intensive operation then you may want to coagulate
  69. the text via Zap_SplitBuffer. The file variables are detailed below. Use
  70. E-Library to set them up.
  71.  
  72. f_ptr
  73. Address of file buffer/-1 if file is dead (has been deleted). If you scan
  74. through the file blocks, you should always check this word to check the file
  75. is not dead.
  76.  
  77. f_bufl
  78. Length of file buffer (multiple of 4). See pic above.
  79.  
  80. f_len
  81. Length of file stored in the buffer (=f_bufl-f_splits).
  82.  
  83. f_name
  84. Pointer to name of the file.
  85.  
  86. f_load
  87. Load address of the file.
  88.  
  89. f_exec
  90. Execution address of the file.
  91.  
  92. f_flags
  93. File flags. See E-Flags for the meaning of the bits in this word.
  94.  
  95. f_uptr
  96. Pointer to the undo buffer. The undo buffer consists of a list of blocks of
  97. variable length. The start of a block is indicated by bit 31 of that word
  98. being set. In general the first word of the block has format:
  99.     b31 =1 (Set to indicate block start).
  100.     b30 Set if the command should be undone in one go. (as opposed to one
  101.         character at a time for concatenated blocks).
  102.     b29 Set if the data pointed to by the command need not be freed.
  103.     (This is used on an undo when blocks are pointed to twice).
  104.     b26-b28 Command number. As for R0 in Zap_Command with additions:
  105.         0 = fast undo pointer (fast redo if b30 set)
  106.         7 = startop pointer (stopop pointer if b30 set)
  107.     b0-b27 Gives the commands first parameter, usually a file offset
  108.         This corresponds to register R1 in Zap_Command.
  109. The other words correspond to registers R2 onwards when calling Zap_Command.
  110.  
  111. f_ubufl
  112. Total length of the undo buffer.
  113.  
  114. f_ulen
  115. Length of valid data in the undo buffer.
  116.  
  117. f_undo
  118. Offset of the undo pointer in the undo buffer.
  119.  
  120. f_undop
  121. Offset of the undo subpointer in the block pointer to by f_undo. Ie it gives
  122. the number of characters left to undo in the operation currently being
  123. undone.
  124.  
  125. f_res3
  126. reserved
  127.  
  128. f_splito
  129. Offset in the file buffer of the current split position. See pic.
  130.  
  131. f_splite
  132. Offset in the file buffer of the end of the current split. See pic.
  133.  
  134. f_splits
  135. Size of the file split (=f_splite-f_splito). See pic.
  136.  
  137. f_mptr
  138. Pointer to the marker buffer. The marker buffer is a list of entries, each
  139. two words longs of the format:
  140.     #0    File offset of the mark
  141.     #4    Window offset of the window mark was place in or -1 if the
  142.         window has been deleted (or is unspecified).
  143.  
  144. f_mbufl
  145. Length of the marker buffer.
  146.  
  147. f_mlen
  148. Length of valid data in the marker buffer.
  149.  
  150. f_mark
  151. Current offset in the marker buffer.
  152.  
  153. f_docom
  154. Used by Zap_SaveTxtStatus: stores the current action (as for Zap_DoCommand
  155. bits 0-2) ie, 1=insert text 2=delete text 3/4=replacement of text.
  156.  
  157. f_source
  158. This word is for the use of the mode 'owning' this file. See f_cmode. It
  159. usually points to a data block of info that mode wants to hold for this file.
  160. Current formats used are:
  161.  f_cmode    f_source meaning
  162.  0 (Text)    Text mode owns external edit files and handles them. f_source
  163.          points to the block:
  164.          #0    External edit JOB handle (Zaps part of the job
  165.              handle is the file block offset+1)
  166.          #4    Task handle of client task
  167.          #8    Flags passed by client when job started
  168.          #12    Offset in window block of associated window.
  169.  1 (Byte)    Byte mode owns 'read disc' files. f_source is the disc
  170.          address the file was read from.
  171.  11 (Throwback) Task handle of task that sent throwback data.
  172.  12(Taskwindow) Taskwindow mode owns taskwindow files. f_source points to
  173.          a block of the format:
  174.          #0    Task handle of child task
  175.          #4    Cursor x posn (chars)
  176.          #8    Cursor y posn (chars)
  177.          #12    Height of emulated screen (chars)
  178.          #16    Text window min x (chars)
  179.          #20    Text window min y (chars)
  180.          #24    Text window max x (chars)
  181.          #28    Text window max y (chars)
  182.          #32    Number of bytes stored in the VDU queue.
  183.          #36    12 byte buffer to store the VDU queue in.
  184.          #48    Offset in window block of associated window.
  185.          #52    Flags:    b0    Set if task suspended
  186.                  b1    internal use
  187.          #56    Line offset from work area start of emulated screen.
  188.         w_bpl stores the width of the emulated screen.
  189.  
  190. f_dolen
  191. Used by Zap_SaveTxtStatus: Stores the size of the data being inserted/
  192. deleted/replaced.
  193.  
  194. f_dodata
  195. Used by Zap_SaveTxtStatus: Stores the address of the data being inserted/
  196. replaced.
  197.  
  198. f_altered
  199. Used by Zap_DoCommand: First altered offset in file / -1
  200.  
  201. f_shiftable
  202. Used by Zap_DoCommand: First unaltered offset in file / -1
  203.  
  204. f_change
  205. Used by Zap_DoCommand: Signed change in size of data.
  206.  
  207. f_depth
  208. Used by Zap_StartOp: Current StartOp/StopOp nested depth.
  209.  
  210. f_links
  211. Links list buffer pointer. This is most used by 'throwback' though may
  212. have other uses. The idea is that this block stores references to offsets
  213. in other files. When these files are updated, the offsets are updated too
  214. so you can keep track of that point in the file. Use Zap_NewLinkEntry to add
  215. a new link. f_links points to a list of 16 byte blocks terminated by -1. The
  216. block format is
  217.     #0    Pointer to file name of associated file (with match/error)
  218.         (Eg this is the C source file corresponding to this throwback
  219.         file).
  220.     #4    Pointer to a list of search/error, offsets/line numbers.
  221.         The list is terminated by -1.
  222.         (These are the offsets to be updated when changes are made
  223.         to the file with name #0 and file block offset in #8).
  224.     #8    Offset of file (name given in #0) if already loaded into Zap.
  225.         -1 if file has not been looked for. If the file is loaded
  226.         then any changes to the file cause the list in #4 to be
  227.         updated.
  228.     #12    Flags:    b0    Set if #4 points to line nums, not offsets.
  229.                 The line numbers are converted to offsets
  230.                 when throwback mode loads the file.
  231.             b1-b7    reserved
  232.             b8-b15    Number of lines heading each block.
  233.                 The format of the throwback buffer must
  234.                 be <file header para> <list of matches para>
  235.                 <next file header para> etc. This details
  236.                 the number of lines of heading/info that the
  237.                 <list of matches para> starts off with
  238.                 before listing the matches (at one match
  239.                 per line corresponding to the offsets
  240.                 pointed to by #4).
  241.             b16-b23    Source: (for info purposes)
  242.                 0=Search throwback (F7)
  243.                 1=C Throwback (Eg !CC)
  244.                 2=C Info (Eg !Find).
  245.             b24-b31 reserved
  246.  
  247. f_cmode
  248. This gives the mode number of the mode 'owning' this file (-1 if none). The
  249. mode is called when the file is deleted (eg a taskwindow). The mode may use
  250. the word f_source to store parameters about the file. (Eg f_source will
  251. usually be set by the extension mode to point to a data block). To claim the
  252. file, simply check that this word is -1 and then poke your mode number in.
  253. Use the entry point e_init with reason code 3 to free any data you have
  254. stored associated with this file (and pointed to by f_source). This mode is
  255. NOT necessarily the mode the file is displayed in.
  256.